/*
   Copyright 2009 Abdulla Abdurakhmanov (abdulla@latestbit.com)
   Original sources are available at www.latestbit.com

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
*/

package org.latestbit.smartobjects;

import org.latestbit.smartobjects.core.*;
import org.latestbit.smartobjects.exceptions.*;
import org.latestbit.smartobjects.network.*;

/**
 * Skeleton (or Server Skeleton) is the server proxy stub 
 * low-level processing all client requests to user server implementation  
 * @author abdulla-a
 *
 */
public interface IServerSkeleton extends ISmartObject {
	/**
	 * Processing client requests thread model
	 * @author abdulla-a
	 *
	 */
	enum ThreadModel {
		/**
		 * All requests proceed sequentially in one thread 
		 */
		SINGLE_THREAD_MODEL,
		/**
		 * All requests proceed in many threads, but sequentially per client  
		 */		
		PER_CLIENT_MULTI_THREAD_MODEL,
		/**
		 * All requests proceed in many threads
		 */				
		FULL_MULTI_THREAD_MODEL
	}
	
	/**
	 * Publishes the skeleton instance on the bus
	 * @param bus ISmartBus instance
	 * @param location Endpoint location (network address/addresses)
	 * @throws SmartBusSystemException
	 */
	void publish( ISmartBus bus, IEndpointLocation location) throws SmartBusSystemException ;

	/**
	 * Publishes the skeleton instance on another published skeleton or resolved remote smart object.  
	 * @param baseObject Another published skeleton or resolved remote smart object
	 * @throws SmartBusSystemException
	 */
	void publish( ISmartObject baseObject ) throws SmartBusSystemException;
	
	/**
	 * Publishes the skeleton instance on another published skeleton or resolved remote smart object 
	 * for specified connection.  
	 * @param baseObject Another published skeleton or resolved remote smart object
	 * @param connectionHandler Connection
	 * @throws SmartBusSystemException
	 */	
	void publish( ISmartObject baseObject, ConnectionHandler connectionHandler ) throws SmartBusSystemException;
	
	/**
	 * Registers this skeleton in the bus skeleton instances registry
	 * @param connectionHandler
	 */
	void registerInstance ( ConnectionHandler connectionHandler );
	
	/**
	 * Unregisters this skeleton from the bus skeleton instances registry
	 */	
	void unregisterInstance ();
	
	/**
	 * Gets current life time control params in the bus skeleton instances registry
	 * @return Current life time control params 
	 */
	LifecycleControlParams getLifecycleControlParams();
	
	/**
	 * Returns published status
	 * @return true - if this skeleton is already published, false - if not
	 */
	boolean isPublished();

	/**
	 * Gets published on location
	 * @return EndpointLocation (network address) where is singleton is published
	 */
	IEndpointLocation getPublishedLocation();
	
	/**
	 * Changes thread model to specified.
	 * @param model Thread model
	 */
	void setThreadModel(ThreadModel model);
	
	/**
	 * Gets current thread model for this skeleton
	 * @return thread model
	 */
	ThreadModel getThreadModel();

	/**
	 * Unpublishes skeleton
	 */
	void unpublish();

	/**
	 * Gets current client requests storage size
	 * @return client requests storage size
	 */
	int getRequestQueueSize();	

}
